metaspn-schemas 0.1.0__tar.gz

metaspn_schemas-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaSPN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metaspn_schemas-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: metaspn-schemas
+Version: 0.1.0
+Summary: Canonical schemas for MetaSPN-compatible signal processing systems
+Author: MetaSPN
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MetaSPN/metaspn-schemas
+Project-URL: Repository, https://github.com/MetaSPN/metaspn-schemas
+Project-URL: Issues, https://github.com/MetaSPN/metaspn-schemas/issues
+Keywords: schemas,signal-processing,events,dataclasses,metaspn
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# metaspn-schemas
+
+Canonical, stdlib-only schema package for MetaSPN-compatible systems.
+
+## Install
+
+```bash
+pip install metaspn-schemas
+```
+
+## Development
+
+```bash
+python -m pip install -e .[dev]
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+## Design constraints
+
+- Tiny and dependency-light (stdlib only)
+- Frozen dataclasses for immutable-by-default objects
+- Explicit `schema_version` on all public objects
+- `to_dict()` / `from_dict()` on every schema
+- UTC ISO-8601 datetime serialization
+- Traceability metadata (`trace_id`, `caused_by`, provenance)
+- Privacy mode support (`to_dict(privacy_mode=True)` omits raw blobs)
+
+## Example
+
+```python
+from datetime import timezone, datetime
+
+from metaspn_schemas import SignalEnvelope
+from metaspn_schemas.utils.ids import generate_id
+
+signal = SignalEnvelope(
+    signal_id=generate_id("signal"),
+    timestamp=datetime.now(timezone.utc),
+    source="linkedin.webhook",
+    payload_type="SocialPostSeen",
+    payload={"post_id": "123", "platform": "linkedin"},
+    schema_version="0.1",
+)
+
+as_dict = signal.to_dict()
+round_trip = SignalEnvelope.from_dict(as_dict)
+```
+
+## Public imports
+
+```python
+from metaspn_schemas import (
+    SignalEnvelope,
+    EmissionEnvelope,
+    Task,
+    Result,
+    SocialPostSeen,
+    ProfileEnriched,
+    ScoresComputed,
+)
+```
+
+## Package layout
+
+```text
+metaspn-schemas/
+  pyproject.toml
+  README.md
+  src/metaspn_schemas/
+    __init__.py
+    core.py
+    tasks.py
+    entities.py
+    social.py
+    outcomes.py
+    features.py
+    state_fragments.py
+    utils/
+      ids.py
+      time.py
+      serde.py
+  test/
+    test_serde.py
+    test_ids.py
+    test_backcompat.py
+```
+
+## Release
+
+Release automation is configured in:
+
+- `.github/workflows/ci.yml`
+- `.github/workflows/publish.yml`
+
+See `RELEASE.md` for the end-to-end push + PyPI release flow.

metaspn_schemas-0.1.0/README.md

@@ -0,0 +1,97 @@
+# metaspn-schemas
+
+Canonical, stdlib-only schema package for MetaSPN-compatible systems.
+
+## Install
+
+```bash
+pip install metaspn-schemas
+```
+
+## Development
+
+```bash
+python -m pip install -e .[dev]
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+## Design constraints
+
+- Tiny and dependency-light (stdlib only)
+- Frozen dataclasses for immutable-by-default objects
+- Explicit `schema_version` on all public objects
+- `to_dict()` / `from_dict()` on every schema
+- UTC ISO-8601 datetime serialization
+- Traceability metadata (`trace_id`, `caused_by`, provenance)
+- Privacy mode support (`to_dict(privacy_mode=True)` omits raw blobs)
+
+## Example
+
+```python
+from datetime import timezone, datetime
+
+from metaspn_schemas import SignalEnvelope
+from metaspn_schemas.utils.ids import generate_id
+
+signal = SignalEnvelope(
+    signal_id=generate_id("signal"),
+    timestamp=datetime.now(timezone.utc),
+    source="linkedin.webhook",
+    payload_type="SocialPostSeen",
+    payload={"post_id": "123", "platform": "linkedin"},
+    schema_version="0.1",
+)
+
+as_dict = signal.to_dict()
+round_trip = SignalEnvelope.from_dict(as_dict)
+```
+
+## Public imports
+
+```python
+from metaspn_schemas import (
+    SignalEnvelope,
+    EmissionEnvelope,
+    Task,
+    Result,
+    SocialPostSeen,
+    ProfileEnriched,
+    ScoresComputed,
+)
+```
+
+## Package layout
+
+```text
+metaspn-schemas/
+  pyproject.toml
+  README.md
+  src/metaspn_schemas/
+    __init__.py
+    core.py
+    tasks.py
+    entities.py
+    social.py
+    outcomes.py
+    features.py
+    state_fragments.py
+    utils/
+      ids.py
+      time.py
+      serde.py
+  test/
+    test_serde.py
+    test_ids.py
+    test_backcompat.py
+```
+
+## Release
+
+Release automation is configured in:
+
+- `.github/workflows/ci.yml`
+- `.github/workflows/publish.yml`
+
+See `RELEASE.md` for the end-to-end push + PyPI release flow.

metaspn_schemas-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metaspn-schemas"
+version = "0.1.0"
+description = "Canonical schemas for MetaSPN-compatible signal processing systems"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "MetaSPN" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["schemas", "signal-processing", "events", "dataclasses", "metaspn"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/MetaSPN/metaspn-schemas"
+Repository = "https://github.com/MetaSPN/metaspn-schemas"
+Issues = "https://github.com/MetaSPN/metaspn-schemas/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2.0", "twine>=5.0.0"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]

metaspn_schemas-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

metaspn_schemas-0.1.0/src/metaspn_schemas/__init__.py

@@ -0,0 +1,46 @@
+from metaspn_schemas.core import (
+    EmissionEnvelope,
+    EntityRef,
+    SchemaVersion,
+    SignalEnvelope,
+    TraceContext,
+)
+from metaspn_schemas.entities import EntityAliasAdded, EntityMerged, EntityResolved
+from metaspn_schemas.features import (
+    GameClassified,
+    PlaybookRouted,
+    ProfileEnriched,
+    ScoresComputed,
+)
+from metaspn_schemas.outcomes import MeetingBooked, MessageSent, ReplyReceived, RevenueEvent
+from metaspn_schemas.social import ProfileSnapshotSeen, SocialPostSeen
+from metaspn_schemas.state_fragments import Attempts, Cooldowns, Evidence, Identity, Scores
+from metaspn_schemas.tasks import Result, Task
+
+__all__ = [
+    "Attempts",
+    "Cooldowns",
+    "EmissionEnvelope",
+    "EntityAliasAdded",
+    "EntityMerged",
+    "EntityRef",
+    "EntityResolved",
+    "Evidence",
+    "GameClassified",
+    "Identity",
+    "MeetingBooked",
+    "MessageSent",
+    "PlaybookRouted",
+    "ProfileEnriched",
+    "ProfileSnapshotSeen",
+    "ReplyReceived",
+    "Result",
+    "RevenueEvent",
+    "SchemaVersion",
+    "Scores",
+    "ScoresComputed",
+    "SignalEnvelope",
+    "SocialPostSeen",
+    "Task",
+    "TraceContext",
+]

metaspn_schemas-0.1.0/src/metaspn_schemas/core.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from metaspn_schemas.utils.serde import Serializable
+from metaspn_schemas.utils.time import ensure_utc
+
+DEFAULT_SCHEMA_VERSION = "0.1"
+
+
+@dataclass(frozen=True)
+class SchemaVersion(Serializable):
+    package: str = "metaspn-schemas"
+    version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class EntityRef(Serializable):
+    ref_type: str
+    value: str
+    platform: str | None = None
+    label: str | None = None
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class TraceContext(Serializable):
+    trace_id: str
+    caused_by: tuple[str, ...] = field(default_factory=tuple)
+    provenance: str | None = None
+    redactions: tuple[str, ...] = field(default_factory=tuple)
+    metadata: dict[str, str] = field(default_factory=dict)
+    privacy_mode: bool = False
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class SignalEnvelope(Serializable):
+    signal_id: str
+    timestamp: datetime
+    source: str
+    payload_type: str
+    payload: Any
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+    entity_refs: tuple[EntityRef, ...] = field(default_factory=tuple)
+    trace: TraceContext | None = None
+    raw: dict[str, Any] | None = field(default=None, metadata={"omit_in_privacy_mode": True})
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "timestamp", ensure_utc(self.timestamp))
+
+
+@dataclass(frozen=True)
+class EmissionEnvelope(Serializable):
+    emission_id: str
+    timestamp: datetime
+    emission_type: str
+    payload: Any
+    caused_by: str
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+    trace: TraceContext | None = None
+    entity_refs: tuple[EntityRef, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "timestamp", ensure_utc(self.timestamp))

metaspn_schemas-0.1.0/src/metaspn_schemas/entities.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from metaspn_schemas.core import DEFAULT_SCHEMA_VERSION
+from metaspn_schemas.utils.serde import Serializable
+
+
+@dataclass(frozen=True)
+class EntityResolved(Serializable):
+    entity_id: str
+    resolver: str
+    resolved_at: datetime
+    confidence: float
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class EntityMerged(Serializable):
+    entity_id: str
+    merged_from: tuple[str, ...]
+    merged_at: datetime
+    reason: str | None = None
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class EntityAliasAdded(Serializable):
+    entity_id: str
+    alias: str
+    alias_type: str
+    added_at: datetime
+    schema_version: str = DEFAULT_SCHEMA_VERSION

metaspn_schemas-0.1.0/src/metaspn_schemas/features.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from metaspn_schemas.core import DEFAULT_SCHEMA_VERSION
+from metaspn_schemas.utils.serde import Serializable
+
+
+@dataclass(frozen=True)
+class ProfileEnriched(Serializable):
+    entity_id: str
+    enriched_at: datetime
+    summary: str
+    topics: tuple[str, ...] = field(default_factory=tuple)
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "topics", tuple(sorted(self.topics)))
+
+
+@dataclass(frozen=True)
+class ScoresComputed(Serializable):
+    entity_id: str
+    computed_at: datetime
+    scores: dict[str, float]
+    scorer: str
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class PlaybookRouted(Serializable):
+    task_id: str
+    routed_at: datetime
+    playbook: str
+    rationale: str | None = None
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class GameClassified(Serializable):
+    entity_id: str
+    classified_at: datetime
+    label: str
+    confidence: float
+    schema_version: str = DEFAULT_SCHEMA_VERSION

metaspn_schemas-0.1.0/src/metaspn_schemas/outcomes.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from metaspn_schemas.core import DEFAULT_SCHEMA_VERSION
+from metaspn_schemas.utils.serde import Serializable
+
+
+@dataclass(frozen=True)
+class MessageSent(Serializable):
+    message_id: str
+    channel: str
+    recipient: str
+    sent_at: datetime
+    subject: str | None = None
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class ReplyReceived(Serializable):
+    reply_id: str
+    message_id: str
+    sender: str
+    received_at: datetime
+    sentiment: str | None = None
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class MeetingBooked(Serializable):
+    meeting_id: str
+    organizer: str
+    booked_at: datetime
+    starts_at: datetime
+    attendees: tuple[str, ...]
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class RevenueEvent(Serializable):
+    revenue_id: str
+    amount: float
+    currency: str
+    recognized_at: datetime
+    source: str
+    schema_version: str = DEFAULT_SCHEMA_VERSION

metaspn_schemas-0.1.0/src/metaspn_schemas/social.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from metaspn_schemas.core import DEFAULT_SCHEMA_VERSION
+from metaspn_schemas.utils.serde import Serializable
+
+
+@dataclass(frozen=True)
+class SocialPostSeen(Serializable):
+    post_id: str
+    platform: str
+    author_handle: str
+    content: str
+    seen_at: datetime
+    url: str | None = None
+    topics: tuple[str, ...] = field(default_factory=tuple)
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "topics", tuple(sorted(self.topics)))
+
+
+@dataclass(frozen=True)
+class ProfileSnapshotSeen(Serializable):
+    profile_id: str
+    platform: str
+    handle: str
+    display_name: str | None
+    bio: str | None
+    seen_at: datetime
+    followers_count: int | None = None
+    topics: tuple[str, ...] = field(default_factory=tuple)
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "topics", tuple(sorted(self.topics)))

metaspn_schemas-0.1.0/src/metaspn_schemas/state_fragments.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from metaspn_schemas.core import DEFAULT_SCHEMA_VERSION
+from metaspn_schemas.utils.serde import Serializable
+
+
+@dataclass(frozen=True)
+class Identity(Serializable):
+    entity_id: str
+    canonical_name: str | None = None
+    aliases: tuple[str, ...] = field(default_factory=tuple)
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class Evidence(Serializable):
+    evidence_id: str
+    entity_id: str
+    source: str
+    collected_at: datetime
+    attributes: dict[str, str] = field(default_factory=dict)
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class Scores(Serializable):
+    entity_id: str
+    values: dict[str, float]
+    updated_at: datetime
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class Cooldowns(Serializable):
+    entity_id: str
+    channel: str
+    until: datetime
+    reason: str | None = None
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class Attempts(Serializable):
+    entity_id: str
+    count: int
+    last_attempt_at: datetime | None = None
+    schema_version: str = DEFAULT_SCHEMA_VERSION

metaspn_schemas-0.1.0/src/metaspn_schemas/tasks.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from metaspn_schemas.core import DEFAULT_SCHEMA_VERSION, EntityRef
+from metaspn_schemas.utils.serde import Serializable
+
+
+@dataclass(frozen=True)
+class Task(Serializable):
+    task_id: str
+    task_type: str
+    created_at: datetime
+    priority: int
+    entity_ref: EntityRef
+    inputs: dict[str, Any] = field(default_factory=dict)
+    context: dict[str, Any] = field(default_factory=dict)
+    schema_version: str = DEFAULT_SCHEMA_VERSION
+
+
+@dataclass(frozen=True)
+class Result(Serializable):
+    result_id: str
+    task_id: str
+    status: str
+    completed_at: datetime
+    outputs: dict[str, Any] = field(default_factory=dict)
+    errors: tuple[str, ...] = field(default_factory=tuple)
+    schema_version: str = DEFAULT_SCHEMA_VERSION

metaspn_schemas-0.1.0/src/metaspn_schemas/utils/__init__.py

@@ -0,0 +1,14 @@
+from metaspn_schemas.utils.ids import generate_id
+from metaspn_schemas.utils.serde import Serializable, dataclass_from_dict, dataclass_to_dict
+from metaspn_schemas.utils.time import datetime_to_str, ensure_utc, str_to_datetime, utc_now
+
+__all__ = [
+    "Serializable",
+    "dataclass_from_dict",
+    "dataclass_to_dict",
+    "datetime_to_str",
+    "ensure_utc",
+    "generate_id",
+    "str_to_datetime",
+    "utc_now",
+]

metaspn_schemas-0.1.0/src/metaspn_schemas/utils/ids.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import uuid
+
+
+VALID_PREFIXES = {
+    "signal": "s",
+    "emission": "e",
+    "task": "t",
+    "result": "r",
+    "entity": "ent",
+}
+
+
+def generate_id(prefix: str | None = None) -> str:
+    token = uuid.uuid4().hex
+    if prefix is None:
+        return token
+    normalized = prefix.strip().lower()
+    mapped = VALID_PREFIXES.get(normalized, normalized)
+    return f"{mapped}_{token}"

metaspn_schemas-0.1.0/src/metaspn_schemas/utils/serde.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import types
+from dataclasses import MISSING, fields, is_dataclass
+from datetime import datetime
+from typing import Any, TypeVar, Union, get_args, get_origin, get_type_hints
+
+from metaspn_schemas.utils.time import datetime_to_str, str_to_datetime
+
+T = TypeVar("T")
+
+
+class Serializable:
+    def to_dict(self, *, privacy_mode: bool = False) -> dict[str, Any]:
+        return dataclass_to_dict(self, privacy_mode=privacy_mode)
+
+    @classmethod
+    def from_dict(cls: type[T], data: dict[str, Any]) -> T:
+        return dataclass_from_dict(cls, data)
+
+
+def dataclass_to_dict(obj: Any, *, privacy_mode: bool = False) -> dict[str, Any]:
+    if not is_dataclass(obj):
+        raise TypeError("dataclass_to_dict expects a dataclass instance")
+
+    output: dict[str, Any] = {}
+    for f in fields(obj):
+        if privacy_mode and f.metadata.get("omit_in_privacy_mode"):
+            continue
+        value = getattr(obj, f.name)
+        output[f.name] = _to_primitive(value, privacy_mode=privacy_mode)
+    return output
+
+
+def _to_primitive(value: Any, *, privacy_mode: bool) -> Any:
+    if is_dataclass(value):
+        return dataclass_to_dict(value, privacy_mode=privacy_mode)
+    if isinstance(value, datetime):
+        return datetime_to_str(value)
+    if isinstance(value, tuple):
+        return [_to_primitive(v, privacy_mode=privacy_mode) for v in value]
+    if isinstance(value, list):
+        return [_to_primitive(v, privacy_mode=privacy_mode) for v in value]
+    if isinstance(value, dict):
+        return {k: _to_primitive(v, privacy_mode=privacy_mode) for k, v in sorted(value.items())}
+    return value
+
+
+def dataclass_from_dict(cls: type[T], data: dict[str, Any]) -> T:
+    if not is_dataclass(cls):
+        raise TypeError("dataclass_from_dict expects a dataclass type")
+
+    hints = get_type_hints(cls)
+    kwargs: dict[str, Any] = {}
+
+    for f in fields(cls):
+        hint = hints.get(f.name, Any)
+        if f.name in data:
+            kwargs[f.name] = _coerce_value(hint, data[f.name])
+            continue
+
+        if f.default is not MISSING:
+            kwargs[f.name] = f.default
+            continue
+
+        if f.default_factory is not MISSING:  # type: ignore[attr-defined]
+            kwargs[f.name] = f.default_factory()  # type: ignore[misc]
+            continue
+
+        raise ValueError(f"Missing required field: {f.name}")
+
+    return cls(**kwargs)
+
+
+def _coerce_value(hint: Any, value: Any) -> Any:
+    if value is None:
+        return None
+
+    origin = get_origin(hint)
+    args = get_args(hint)
+
+    if hint is Any:
+        return value
+
+    if hint is datetime:
+        if isinstance(value, datetime):
+            return value
+        if isinstance(value, str):
+            return str_to_datetime(value)
+        raise TypeError(f"Cannot parse datetime from {type(value)!r}")
+
+    if origin in (Union, types.UnionType):
+        last_error: Exception | None = None
+        for option in args:
+            if option is type(None):
+                continue
+            try:
+                return _coerce_value(option, value)
+            except Exception as err:  # noqa: BLE001
+                last_error = err
+        if last_error is not None:
+            raise last_error
+        return value
+
+    if origin is tuple:
+        item_type = args[0] if args else Any
+        return tuple(_coerce_value(item_type, item) for item in value)
+
+    if origin is list:
+        item_type = args[0] if args else Any
+        return [_coerce_value(item_type, item) for item in value]
+
+    if origin is dict:
+        key_type = args[0] if len(args) > 0 else Any
+        value_type = args[1] if len(args) > 1 else Any
+        return {
+            _coerce_value(key_type, k): _coerce_value(value_type, v)
+            for k, v in value.items()
+        }
+
+    if is_dataclass(hint):
+        if isinstance(value, hint):
+            return value
+        if isinstance(value, dict):
+            return dataclass_from_dict(hint, value)
+
+    if hint in (str, int, float, bool):
+        return hint(value)
+
+    return value

metaspn_schemas-0.1.0/src/metaspn_schemas/utils/time.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def ensure_utc(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+def datetime_to_str(value: datetime) -> str:
+    utc_value = ensure_utc(value)
+    return utc_value.isoformat().replace("+00:00", "Z")
+
+
+def str_to_datetime(value: str) -> datetime:
+    text = value[:-1] + "+00:00" if value.endswith("Z") else value
+    parsed = datetime.fromisoformat(text)
+    return ensure_utc(parsed)

metaspn_schemas-0.1.0/src/metaspn_schemas.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: metaspn-schemas
+Version: 0.1.0
+Summary: Canonical schemas for MetaSPN-compatible signal processing systems
+Author: MetaSPN
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MetaSPN/metaspn-schemas
+Project-URL: Repository, https://github.com/MetaSPN/metaspn-schemas
+Project-URL: Issues, https://github.com/MetaSPN/metaspn-schemas/issues
+Keywords: schemas,signal-processing,events,dataclasses,metaspn
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# metaspn-schemas
+
+Canonical, stdlib-only schema package for MetaSPN-compatible systems.
+
+## Install
+
+```bash
+pip install metaspn-schemas
+```
+
+## Development
+
+```bash
+python -m pip install -e .[dev]
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+## Design constraints
+
+- Tiny and dependency-light (stdlib only)
+- Frozen dataclasses for immutable-by-default objects
+- Explicit `schema_version` on all public objects
+- `to_dict()` / `from_dict()` on every schema
+- UTC ISO-8601 datetime serialization
+- Traceability metadata (`trace_id`, `caused_by`, provenance)
+- Privacy mode support (`to_dict(privacy_mode=True)` omits raw blobs)
+
+## Example
+
+```python
+from datetime import timezone, datetime
+
+from metaspn_schemas import SignalEnvelope
+from metaspn_schemas.utils.ids import generate_id
+
+signal = SignalEnvelope(
+    signal_id=generate_id("signal"),
+    timestamp=datetime.now(timezone.utc),
+    source="linkedin.webhook",
+    payload_type="SocialPostSeen",
+    payload={"post_id": "123", "platform": "linkedin"},
+    schema_version="0.1",
+)
+
+as_dict = signal.to_dict()
+round_trip = SignalEnvelope.from_dict(as_dict)
+```
+
+## Public imports
+
+```python
+from metaspn_schemas import (
+    SignalEnvelope,
+    EmissionEnvelope,
+    Task,
+    Result,
+    SocialPostSeen,
+    ProfileEnriched,
+    ScoresComputed,
+)
+```
+
+## Package layout
+
+```text
+metaspn-schemas/
+  pyproject.toml
+  README.md
+  src/metaspn_schemas/
+    __init__.py
+    core.py
+    tasks.py
+    entities.py
+    social.py
+    outcomes.py
+    features.py
+    state_fragments.py
+    utils/
+      ids.py
+      time.py
+      serde.py
+  test/
+    test_serde.py
+    test_ids.py
+    test_backcompat.py
+```
+
+## Release
+
+Release automation is configured in:
+
+- `.github/workflows/ci.yml`
+- `.github/workflows/publish.yml`
+
+See `RELEASE.md` for the end-to-end push + PyPI release flow.

metaspn_schemas-0.1.0/src/metaspn_schemas.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+src/metaspn_schemas/__init__.py
+src/metaspn_schemas/core.py
+src/metaspn_schemas/entities.py
+src/metaspn_schemas/features.py
+src/metaspn_schemas/outcomes.py
+src/metaspn_schemas/social.py
+src/metaspn_schemas/state_fragments.py
+src/metaspn_schemas/tasks.py
+src/metaspn_schemas.egg-info/PKG-INFO
+src/metaspn_schemas.egg-info/SOURCES.txt
+src/metaspn_schemas.egg-info/dependency_links.txt
+src/metaspn_schemas.egg-info/requires.txt
+src/metaspn_schemas.egg-info/top_level.txt
+src/metaspn_schemas/utils/__init__.py
+src/metaspn_schemas/utils/ids.py
+src/metaspn_schemas/utils/serde.py
+src/metaspn_schemas/utils/time.py
+test/test_backcompat.py
+test/test_ids.py
+test/test_serde.py

metaspn_schemas-0.1.0/src/metaspn_schemas.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

metaspn_schemas-0.1.0/src/metaspn_schemas.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=8
+build>=1.2.0
+twine>=5.0.0

metaspn_schemas-0.1.0/src/metaspn_schemas.egg-info/top_level.txt

@@ -0,0 +1 @@
+metaspn_schemas

metaspn_schemas-0.1.0/test/test_backcompat.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from metaspn_schemas.core import SignalEnvelope
+
+
+def test_signal_backcompat_prior_minor_payload() -> None:
+    legacy_payload = {
+        "signal_id": "s_legacy",
+        "timestamp": "2025-01-01T10:30:00Z",
+        "source": "legacy.source",
+        "payload_type": "SocialPostSeen",
+        "payload": {"post_id": "p1"},
+        "schema_version": "0.0",
+    }
+
+    signal = SignalEnvelope.from_dict(legacy_payload)
+
+    assert signal.signal_id == "s_legacy"
+    assert signal.timestamp == datetime(2025, 1, 1, 10, 30, tzinfo=timezone.utc)
+    assert signal.entity_refs == ()
+    assert signal.trace is None
+    assert signal.raw is None

metaspn_schemas-0.1.0/test/test_ids.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from metaspn_schemas.utils.ids import generate_id
+
+
+def test_generate_id_default() -> None:
+    value = generate_id()
+    assert "_" not in value
+    assert len(value) == 32
+
+
+def test_generate_id_with_known_prefix() -> None:
+    value = generate_id("signal")
+    assert value.startswith("s_")
+    assert len(value.split("_", 1)[1]) == 32
+
+
+def test_generate_id_with_custom_prefix() -> None:
+    value = generate_id("custom")
+    assert value.startswith("custom_")

metaspn_schemas-0.1.0/test/test_serde.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from metaspn_schemas.core import EmissionEnvelope, EntityRef, SchemaVersion, SignalEnvelope, TraceContext
+from metaspn_schemas.entities import EntityAliasAdded, EntityMerged, EntityResolved
+from metaspn_schemas.features import GameClassified, PlaybookRouted, ProfileEnriched, ScoresComputed
+from metaspn_schemas.outcomes import MeetingBooked, MessageSent, ReplyReceived, RevenueEvent
+from metaspn_schemas.social import ProfileSnapshotSeen, SocialPostSeen
+from metaspn_schemas.state_fragments import Attempts, Cooldowns, Evidence, Identity, Scores
+from metaspn_schemas.tasks import Result, Task
+
+NOW = datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc)
+
+
+def assert_round_trip(instance: object, cls: type) -> None:
+    as_dict = instance.to_dict()
+    rebuilt = cls.from_dict(as_dict)
+    assert rebuilt == instance
+
+
+def test_round_trip_core_schemas() -> None:
+    entity_ref = EntityRef(ref_type="entity_id", value="ent_1")
+    trace = TraceContext(
+        trace_id="tr_1",
+        caused_by=("s_1",),
+        provenance="ingestor",
+        redactions=("content",),
+        metadata={"a": "1", "b": "2"},
+    )
+    signal = SignalEnvelope(
+        signal_id="s_1",
+        timestamp=NOW,
+        source="source",
+        payload_type="SocialPostSeen",
+        payload={"b": 2, "a": 1},
+        entity_refs=(entity_ref,),
+        trace=trace,
+        raw={"secret": "raw"},
+    )
+    emission = EmissionEnvelope(
+        emission_id="e_1",
+        timestamp=NOW,
+        emission_type="ScoresComputed",
+        payload={"score": 0.9},
+        caused_by="s_1",
+        trace=trace,
+        entity_refs=(entity_ref,),
+    )
+
+    assert_round_trip(SchemaVersion(), SchemaVersion)
+    assert_round_trip(entity_ref, EntityRef)
+    assert_round_trip(trace, TraceContext)
+    assert_round_trip(signal, SignalEnvelope)
+    assert_round_trip(emission, EmissionEnvelope)
+
+
+def test_round_trip_task_contracts() -> None:
+    task = Task(
+        task_id="t_1",
+        task_type="enrich.profile",
+        created_at=NOW,
+        priority=1,
+        entity_ref=EntityRef(ref_type="email", value="x@example.com"),
+        inputs={"x": 1},
+        context={"team": "growth"},
+    )
+    result = Result(
+        result_id="r_1",
+        task_id="t_1",
+        status="ok",
+        completed_at=NOW,
+        outputs={"done": True},
+        errors=(),
+    )
+
+    assert_round_trip(task, Task)
+    assert_round_trip(result, Result)
+
+
+def test_round_trip_social_outcomes_entities_features_state_fragments() -> None:
+    instances = [
+        SocialPostSeen("p1", "linkedin", "@a", "hello", NOW, topics=("b", "a")),
+        ProfileSnapshotSeen("pr1", "linkedin", "@a", "A", "Bio", NOW, topics=("x", "c")),
+        MessageSent("m1", "email", "x@example.com", NOW),
+        ReplyReceived("rp1", "m1", "y@example.com", NOW),
+        MeetingBooked("mt1", "x@example.com", NOW, NOW, ("a", "b")),
+        RevenueEvent("rev1", 120.5, "USD", NOW, "stripe"),
+        EntityResolved("ent1", "resolver", NOW, 0.91),
+        EntityMerged("ent1", ("ent2", "ent3"), NOW, "dedupe"),
+        EntityAliasAdded("ent1", "acme", "domain", NOW),
+        ProfileEnriched("ent1", NOW, "summary", topics=("go", "ai")),
+        ScoresComputed("ent1", NOW, {"fit": 0.88}, "v1"),
+        PlaybookRouted("t1", NOW, "warm_outbound"),
+        GameClassified("ent1", NOW, "six_games", 0.77),
+        Identity("ent1", "Acme", ("Acme Inc",)),
+        Evidence("ev1", "ent1", "web", NOW, {"domain": "acme.com"}),
+        Scores("ent1", {"intent": 0.2}, NOW),
+        Cooldowns("ent1", "email", NOW),
+        Attempts("ent1", 2, NOW),
+    ]
+    classes = [
+        SocialPostSeen,
+        ProfileSnapshotSeen,
+        MessageSent,
+        ReplyReceived,
+        MeetingBooked,
+        RevenueEvent,
+        EntityResolved,
+        EntityMerged,
+        EntityAliasAdded,
+        ProfileEnriched,
+        ScoresComputed,
+        PlaybookRouted,
+        GameClassified,
+        Identity,
+        Evidence,
+        Scores,
+        Cooldowns,
+        Attempts,
+    ]
+
+    for instance, cls in zip(instances, classes, strict=True):
+        assert_round_trip(instance, cls)
+
+
+def test_datetime_serialization_format_is_utc_iso8601() -> None:
+    signal = SignalEnvelope(
+        signal_id="s_utc",
+        timestamp=NOW,
+        source="test",
+        payload_type="x",
+        payload={},
+    )
+
+    data = signal.to_dict()
+    assert data["timestamp"] == "2026-01-01T12:00:00Z"
+
+
+def test_privacy_mode_omits_raw_blob() -> None:
+    signal = SignalEnvelope(
+        signal_id="s_priv",
+        timestamp=NOW,
+        source="test",
+        payload_type="x",
+        payload={},
+        raw={"body": "sensitive"},
+    )
+
+    data = signal.to_dict(privacy_mode=True)
+    assert "raw" not in data
+
+
+def test_deterministic_dict_key_ordering() -> None:
+    signal = SignalEnvelope(
+        signal_id="s_ord",
+        timestamp=NOW,
+        source="test",
+        payload_type="x",
+        payload={"z": {"b": 2, "a": 1}, "a": 10},
+    )
+
+    payload = signal.to_dict()["payload"]
+    assert list(payload.keys()) == ["a", "z"]
+    assert list(payload["z"].keys()) == ["a", "b"]
+
+
+def test_topic_lists_are_sorted_on_construction() -> None:
+    post = SocialPostSeen("p", "x", "@u", "c", NOW, topics=("ml", "ai"))
+    enriched = ProfileEnriched("ent", NOW, "s", topics=("z", "a"))
+
+    assert post.topics == ("ai", "ml")
+    assert enriched.topics == ("a", "z")