matyan_api_models 0.1.0__tar.gz

matyan_api_models-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: matyan_api_models
+Version: 0.1.0
+Summary: Models for the Matyan API
+Author-email: Tigran Grigoryan <grigoryan.tigran119@gmail.com>
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic~=2.0

matyan_api_models-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matyan_api_models"
+version = "0.1.0"
+description = "Models for the Matyan API"
+readme = "README.md"
+authors = [
+    { name = "Tigran Grigoryan", email = "grigoryan.tigran119@gmail.com" },
+]
+requires-python = ">=3.10, <4"
+dependencies = ["pydantic~=2.0"]
+
+[dependency-groups]
+dev = ["mypy~=1.15"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "FBT001",
+    "FBT002",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D105",
+    "D106",
+    "D107",
+    "D203",
+    "D213",
+    "D417",
+    "FBT003",
+    "EXE002",
+    "S311",
+    "TD003",
+    "D205",
+    "PLR2004",
+    "PLR0913",
+    "S101",
+    "S104",
+]

matyan_api_models-0.1.0/setup.cfg

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

matyan_api_models-0.1.0/src/matyan_api_models/__init__.py

@@ -0,0 +1,10 @@
+from .responses import LogHParamsResponse, LogMetricResponse, ReadMetricResponse
+from .run_creation import RunCreateRequest, RunCreateResponse
+
+__all__ = [
+    "LogHParamsResponse",
+    "LogMetricResponse",
+    "ReadMetricResponse",
+    "RunCreateRequest",
+    "RunCreateResponse",
+]

matyan_api_models-0.1.0/src/matyan_api_models/kafka/__init__.py

@@ -0,0 +1,3 @@
+from ._messages import ControlEvent, IngestionMessage
+
+__all__ = ["ControlEvent", "IngestionMessage"]

matyan_api_models-0.1.0/src/matyan_api_models/kafka/_messages.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import datetime  # noqa: TC003
+
+from pydantic import BaseModel
+
+
+class IngestionMessage(BaseModel):
+    """Envelope for all messages on the ``data-ingestion`` Kafka topic.
+
+    Both frontier (producer) and ingestion workers (consumer) depend on this
+    schema.  The ``type`` field discriminates the payload shape.
+    """
+
+    type: str
+    run_id: str
+    timestamp: datetime
+    payload: dict
+
+
+class ControlEvent(BaseModel):
+    """Envelope for all messages on the ``control-events`` Kafka topic.
+
+    Published by the backend API after synchronous FDB writes.
+    Consumed by control workers for async side effects (S3 cleanup, etc.).
+    """
+
+    type: str
+    timestamp: datetime
+    payload: dict

matyan_api_models-0.1.0/src/matyan_api_models/responses.py

@@ -0,0 +1,18 @@
+from pydantic import BaseModel
+
+
+class ReadMetricResponse(BaseModel):
+    value: float
+    timestamp: int
+
+
+class ReadHParamsResponse(BaseModel):
+    value: dict
+
+
+class LogHParamsResponse(BaseModel):
+    status: int
+
+
+class LogMetricResponse(BaseModel):
+    status: int

matyan_api_models-0.1.0/src/matyan_api_models/run_creation.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import re
+import uuid
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class RunCreateRequest(BaseModel):
+    id: str
+    project: str = Field(min_length=1)
+    experiment: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    description: str
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, value: str) -> str:
+        # Ensure it contains only valid hexadecimal characters
+        if not re.fullmatch(r"[0-9a-f]{32}", value):
+            msg = "UUID must be a 32-character hexadecimal lowercase string"
+            raise ValueError(msg)
+
+        try:
+            _ = uuid.UUID(hex=value)
+        except ValueError as e:
+            msg = "Not a valid UUID hex format"
+            raise ValueError(msg) from e
+
+        return value
+
+
+class RunCreateResponse(BaseModel):
+    creation_timestamp: int

matyan_api_models-0.1.0/src/matyan_api_models/typing/__init__.py

@@ -0,0 +1,29 @@
+from ._main import (
+    ContextT,
+    DescriptionT,
+    DtypeT,
+    EpochT,
+    ExperimentNameT,
+    HParams,
+    MetricT,
+    ProjectNameT,
+    RunId,
+    RunIdT,
+    RunNameT,
+    StepT,
+)
+
+__all__ = [
+    "ContextT",
+    "DescriptionT",
+    "DtypeT",
+    "EpochT",
+    "ExperimentNameT",
+    "HParams",
+    "MetricT",
+    "ProjectNameT",
+    "RunId",
+    "RunIdT",
+    "RunNameT",
+    "StepT",
+]

matyan_api_models-0.1.0/src/matyan_api_models/typing/_main.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Annotated, Any
+
+from pydantic import BeforeValidator
+
+
+def _validate_run_id(value: str | None) -> str:
+    if value is None:
+        return uuid.uuid4().hex
+
+    # Ensure it contains only valid hexadecimal characters
+    if not re.fullmatch(r"[0-9a-f]{32}", value):
+        msg = "UUID must be a 32-character hexadecimal lowercase string"
+        raise ValueError(msg)
+
+    try:
+        _ = uuid.UUID(hex=value)
+    except ValueError as e:
+        msg = "Not a valid UUID hex format"
+        raise ValueError(msg) from e
+
+    return value
+
+
+RunId = Annotated[str, BeforeValidator(_validate_run_id)]
+RunIdT = str
+RunNameT = str
+ProjectNameT = str
+ExperimentNameT = str
+DescriptionT = str
+
+MetricNameT = str
+StepT = int
+EpochT = int
+ContextT = dict
+DtypeT = str
+MetricT = str
+HParams = dict[str, Any]

matyan_api_models-0.1.0/src/matyan_api_models/ws/__init__.py

@@ -0,0 +1,33 @@
+from ._requests import (
+    AddTagWsRequest,
+    BaseWsRequest,
+    CreateRunWsRequest,
+    FinishRunWsRequest,
+    LogCustomObjectWsRequest,
+    LogHParamsWsRequest,
+    LogMetricWsRequest,
+    LogRecordWsRequest,
+    LogTerminalLineWsRequest,
+    RemoveTagWsRequest,
+    SetRunPropertyWsRequest,
+    WsRequestT,
+    WsRequestTAdapter,
+)
+from ._responses import WsResponse
+
+__all__ = [
+    "AddTagWsRequest",
+    "BaseWsRequest",
+    "CreateRunWsRequest",
+    "FinishRunWsRequest",
+    "LogCustomObjectWsRequest",
+    "LogHParamsWsRequest",
+    "LogMetricWsRequest",
+    "LogRecordWsRequest",
+    "LogTerminalLineWsRequest",
+    "RemoveTagWsRequest",
+    "SetRunPropertyWsRequest",
+    "WsRequestT",
+    "WsRequestTAdapter",
+    "WsResponse",
+]

matyan_api_models-0.1.0/src/matyan_api_models/ws/_requests.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from datetime import datetime  # noqa: TC003
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, TypeAdapter
+
+
+class BaseWsRequest(BaseModel):
+    type: str
+    run_id: str
+
+
+class CreateRunWsRequest(BaseWsRequest):
+    type: Literal["create_run"] = "create_run"
+    client_datetime: datetime
+    force_resume: bool = False
+
+
+class LogMetricWsRequest(BaseWsRequest):
+    type: Literal["log_metric"] = "log_metric"
+    name: str
+    value: float
+    step: int | None
+    epoch: int | None
+    context: dict | None
+    dtype: str | None
+    client_datetime: datetime
+
+
+class LogHParamsWsRequest(BaseWsRequest):
+    type: Literal["log_hparams"] = "log_hparams"
+    value: dict
+
+
+class FinishRunWsRequest(BaseWsRequest):
+    type: Literal["finish_run"] = "finish_run"
+
+
+class SetRunPropertyWsRequest(BaseWsRequest):
+    """Set one or more run properties (name, description, archived, experiment)."""
+
+    type: Literal["set_run_property"] = "set_run_property"
+    name: str | None = None
+    description: str | None = None
+    archived: bool | None = None
+    experiment: str | None = None
+
+
+class AddTagWsRequest(BaseWsRequest):
+    """Add a tag to a run (by tag name — will be created if it doesn't exist)."""
+
+    type: Literal["add_tag"] = "add_tag"
+    tag_name: str
+
+
+class RemoveTagWsRequest(BaseWsRequest):
+    """Remove a tag from a run (by tag name)."""
+
+    type: Literal["remove_tag"] = "remove_tag"
+    tag_name: str
+
+
+class LogCustomObjectWsRequest(BaseWsRequest):
+    """Track a custom object (Image, Audio, Text, Distribution, Figure).
+
+    ``value`` carries the serialized metadata dict (and for blob types, the
+    ``s3_key`` referencing the already-uploaded binary data).
+    """
+
+    type: Literal["log_custom_object"] = "log_custom_object"
+    name: str
+    value: dict
+    step: int | None = None
+    epoch: int | None = None
+    context: dict | None = None
+    dtype: str = "custom"
+    client_datetime: datetime | None = None
+
+
+class LogTerminalLineWsRequest(BaseWsRequest):
+    """A single captured terminal output line (stdout/stderr)."""
+
+    type: Literal["log_terminal_line"] = "log_terminal_line"
+    line: str
+    step: int
+
+
+class LogRecordWsRequest(BaseWsRequest):
+    """A structured log record (log_info / log_warning / log_error / log_debug)."""
+
+    type: Literal["log_record"] = "log_record"
+    message: str
+    level: int
+    timestamp: float
+    logger_info: list | None = None
+    extra_args: dict | None = None
+
+
+WsRequestT = Annotated[
+    CreateRunWsRequest
+    | LogMetricWsRequest
+    | LogHParamsWsRequest
+    | FinishRunWsRequest
+    | SetRunPropertyWsRequest
+    | AddTagWsRequest
+    | RemoveTagWsRequest
+    | LogCustomObjectWsRequest
+    | LogTerminalLineWsRequest
+    | LogRecordWsRequest,
+    Field(discriminator="type"),
+]
+
+
+WsRequestTAdapter: TypeAdapter[WsRequestT] = TypeAdapter(WsRequestT)  # ty:ignore[invalid-assignment]

matyan_api_models-0.1.0/src/matyan_api_models/ws/_responses.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class WsResponse(BaseModel):
+    status: str
+    error: str | None = None

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

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: matyan_api_models
+Version: 0.1.0
+Summary: Models for the Matyan API
+Author-email: Tigran Grigoryan <grigoryan.tigran119@gmail.com>
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic~=2.0

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

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/matyan_api_models/__init__.py
+src/matyan_api_models/py.typed
+src/matyan_api_models/responses.py
+src/matyan_api_models/run_creation.py
+src/matyan_api_models.egg-info/PKG-INFO
+src/matyan_api_models.egg-info/SOURCES.txt
+src/matyan_api_models.egg-info/dependency_links.txt
+src/matyan_api_models.egg-info/requires.txt
+src/matyan_api_models.egg-info/top_level.txt
+src/matyan_api_models/kafka/__init__.py
+src/matyan_api_models/kafka/_messages.py
+src/matyan_api_models/typing/__init__.py
+src/matyan_api_models/typing/_main.py
+src/matyan_api_models/ws/__init__.py
+src/matyan_api_models/ws/_requests.py
+src/matyan_api_models/ws/_responses.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+pydantic~=2.0

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

@@ -0,0 +1 @@
+matyan_api_models