mmar-mapi 1.0.0__tar.gz

mmar_mapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AIRI
+
+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.

mmar_mapi-1.0.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: mmar-mapi
+Version: 1.0.0
+Summary: Common pure/IO utilities for multi-modal architectures team
+Keywords: 
+Author: Eugene Tagin
+Author-email: Eugene Tagin <tagin@airi.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.9.2,<=3.0.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# mmar-mapi
+
+Multimodal architectures Maestro API

mmar_mapi-1.0.0/README.md

@@ -0,0 +1,3 @@
+# mmar-mapi
+
+Multimodal architectures Maestro API

mmar_mapi-1.0.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "mmar-mapi"
+# dynamic version is not supported yet on uv_build
+version = "1.0.0"
+description = "Common pure/IO utilities for multi-modal architectures team"
+authors = [{name = "Eugene Tagin", email = "tagin@airi.net"}]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.9.2,<=3.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.14,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mmar_mapi"
+source-exclude = [".ruff_cache"]
+
+[dependency-groups]
+maintain = [
+    "build>=1.2",
+    "git-changelog>=2.5",
+    "twine>=5.1",
+    "yore>=0.3.3",
+]
+ci = [
+    "ruff>=0.4",
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "pytest-randomly>=3.15",
+    "pytest-asyncio>=1.0.0",
+    "mypy>=1.10",
+    "types-markdown>=3.6",
+    "types-pyyaml>=6.0",
+]
+
+[tool.uv]
+default-groups = ["maintain", "ci"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[pytest]
+pythonpath = "src"
+python_files = [ "test_*.py" ]
+testpaths = [ "tests" ]
+
+# action:message_regex:warning_class:module_regex:line
+filterwarnings = [ "error" ]
+
+[mypy]
+ignore_missing_imports = true
+exclude = "tests/fixtures/"
+warn_unused_ignores = true
+show_error_codes = true

mmar_mapi-1.0.0/src/mmar_mapi/__init__.py

@@ -0,0 +1,11 @@
+__version__ = "5.2.4"
+
+from .file_storage import FileStorage, ResourceId
+from .models.base import Base
+from .models.base_config_models import GigaChatConfig
+from .models.chat import Chat, Context, ChatMessage, AIMessage, HumanMessage, MiscMessage, make_content
+from .models.chat_item import ChatItem, OuterContextItem, InnerContextItem, ReplicaItem
+from .models.enums import MTRSLabelEnum, DiagnosticsXMLTagEnum, MTRSXMLTagEnum, DoctorChoiceXMLTagEnum
+from .models.tracks import TrackInfo, DomainInfo
+from .models.widget import Widget
+from .utils import make_session_id

mmar_mapi-1.0.0/src/mmar_mapi/api.py

@@ -0,0 +1,62 @@
+from mmar_mapi.models.chat import Chat, ChatMessage
+from mmar_mapi.models.tracks import DomainInfo, TrackInfo
+from pydantic import BaseModel
+
+
+Value = str
+Interpretation = str
+ResourceId = str
+
+
+class ChatManagerAPI:
+    def get_domains(self, *, client_id: str, language_code: str = "ru") -> list[DomainInfo]:
+        raise NotImplementedError
+
+    def get_tracks(self, *, client_id: str, language_code: str = "ru") -> list[TrackInfo]:
+        raise NotImplementedError
+
+    def get_response(self, *, chat: Chat) -> list[ChatMessage]:
+        raise NotImplementedError
+
+
+class TextGeneratorAPI:
+    def process(self, *, chat: Chat) -> str:
+        raise NotImplementedError
+
+
+class ContentInterpreterRemoteResponse(BaseModel):
+    interpretation: str
+    resource_fname: str
+    resource: bytes
+
+
+class ContentInterpreterRemoteAPI:
+    def interpret_remote(
+        self, *, kind: str, query: str, resource: bytes, chat: Chat | None = None
+    ) -> ContentInterpreterRemoteResponse:
+        raise NotImplementedError
+
+
+class ClassifierAPI:
+    def get_values(self) -> list[Value]:
+        raise NotImplementedError
+
+    def evaluate(self, *, chat: Chat) -> Value:
+        raise NotImplementedError
+
+
+class CriticAPI:
+    def evaluate(self, *, text: str, chat: Chat | None = None) -> float:
+        raise NotImplementedError
+
+
+class ContentInterpreterAPI:
+    def interpret(
+        self, *, kind: str, query: str, resource_id: str = "", chat: Chat | None = None
+    ) -> tuple[Interpretation, ResourceId | None]:
+        raise NotImplementedError
+
+
+class TextProcessorAPI:
+    def process(self, *, text: str, chat: Chat | None = None) -> str:
+        raise NotImplementedError

mmar_mapi-1.0.0/src/mmar_mapi/file_storage.py

@@ -0,0 +1,113 @@
+import string
+from hashlib import md5
+from pathlib import Path
+from zipfile import ZipFile, is_zipfile
+
+
+ResourceId = str
+ASCII_DIGITS = set(string.ascii_lowercase + string.digits)
+SUFFIX_DIR = ".dir"
+
+
+def _validate_exist(files_dir):
+    if not files_dir.exists():
+        err = f"Failed to access file-storage directory: {files_dir}"
+        raise OSError(err)
+
+
+def _validate_dtype(dtype: str):
+    if all(map(ASCII_DIGITS.__contains__, dtype)):
+        return
+    raise ValueError(f"Bad dtype: {dtype}")
+
+
+def generate_fname(content, dtype):
+    fname_hash = md5(content).hexdigest()
+    fname = f"{fname_hash}.{dtype}"
+    return fname
+
+
+class FileStorage:
+    def __init__(self, files_dir):
+        self.files_dir = Path(files_dir)
+        self.files_dir.mkdir(exist_ok=True, parents=True)
+        _validate_exist(self.files_dir)
+
+    def _generate_fname_path(self, content: bytes, dtype: str):
+        fpath = self.files_dir / generate_fname(content, dtype)
+        return fpath
+
+    def upload_maybe(self, content: bytes | None, dtype: str) -> ResourceId | None:
+        if not content:
+            return None
+        resource_id = self.upload(content, dtype)
+        return resource_id
+
+    def upload(self, content: bytes | str, dtype: str) -> ResourceId:
+        _validate_dtype(dtype)
+        if isinstance(content, str):
+            content = content.encode()
+        fpath = self._generate_fname_path(content, dtype)
+        fpath.write_bytes(content)
+        return str(fpath)
+
+    def upload_dir(self, resource_ids: list[ResourceId]) -> ResourceId:
+        content = "\n".join(resource_ids)
+        res = self.upload(content, "dir")
+        return res
+
+    def download(self, resource_id: ResourceId) -> bytes:
+        return Path(resource_id).read_bytes()
+
+    def download_text(self, resource_id: ResourceId) -> str:
+        return Path(resource_id).read_text(encoding="utf-8")
+
+    def read_dir_or_none(self, resource_id: ResourceId) -> list[ResourceId] | None:
+        if not self.is_dir(resource_id):
+            return None
+        res = self.download_text(resource_id).split("\n")
+        return res
+
+    def _get_path(self, resource_id: ResourceId | None) -> Path | None:
+        if not resource_id:
+            return None
+        path = Path(resource_id)
+        return path if (path.exists() and path.is_file()) else None
+
+    def is_valid(self, resource_id: ResourceId | None) -> bool:
+        path = self._get_path(resource_id)
+        return path is not None
+
+    def is_file(self, resource_id: ResourceId | None) -> bool:
+        path = self._get_path(resource_id)
+        return path and path.suffix != SUFFIX_DIR
+
+    def is_dir(self, resource_id: ResourceId | None) -> bool:
+        path = self._get_path(resource_id)
+        return path and path.suffix == SUFFIX_DIR
+
+    def get_dtype(self, resource_id: ResourceId | None) -> str | None:
+        return resource_id and resource_id.rsplit(".")[-1]
+
+    def unzip_file(self, resource_id: str) -> ResourceId:
+        """ takes resource_id which refer to zip-archive, unpacks it and returns directory ResourceId with content of zip-archive """
+        path = self._get_path(resource_id)
+        if not path:
+            raise ValueError(f"Not found path: {resource_id}")
+        if not is_zipfile(resource_id):
+            raise ValueError(f"Expected zip archive but found: {resource_id}")
+
+        resource_ids = []
+
+        with ZipFile(path, mode='r') as zip_file:
+            files_info = zip_file.filelist
+
+            for file_info in zip_file.filelist:
+                file_dtype = file_info.filename.rsplit('.')[-1]
+                file_bytes = zip_file.read(file_info)
+                rid = self.upload(file_bytes, file_dtype)
+                resource_ids.append(rid)
+
+        res = self.upload_dir(resource_ids)
+        return res
+                

mmar_mapi-1.0.0/src/mmar_mapi/models/base.py

@@ -0,0 +1,15 @@
+import json
+from typing import Any
+
+from pydantic import ConfigDict, BaseModel, model_validator
+
+
+class Base(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, str_strip_whitespace=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_to_json(cls, value: str | Any) -> Any:
+        if isinstance(value, str):
+            return cls(**json.loads(value))
+        return value

mmar_mapi-1.0.0/src/mmar_mapi/models/base_config_models/__init__.py

@@ -0,0 +1 @@
+from .gigachat_config import GigaChatConfig

mmar_mapi-1.0.0/src/mmar_mapi/models/base_config_models/gigachat_config.py

@@ -0,0 +1,14 @@
+from typing import Self
+
+from pydantic import BaseModel, model_validator, SecretStr
+
+
+class GigaChatConfig(BaseModel):
+    client_id: SecretStr = SecretStr("")
+    client_secret: SecretStr = SecretStr("")
+
+    @model_validator(mode="after")
+    def empty_validator(self) -> Self:
+        if not (self.client_id and self.client_secret):
+            raise ValueError("creds for gigachat is not filled")
+        return self

mmar_mapi-1.0.0/src/mmar_mapi/models/chat.py

@@ -0,0 +1,399 @@
+import warnings
+from copy import deepcopy
+from datetime import datetime
+from typing import Any, Literal, TypeVar
+from collections.abc import Callable
+
+from mmar_mapi.models.chat_item import ChatItem, ReplicaItem, OuterContextItem
+from mmar_mapi.models.widget import Widget
+from mmar_mapi.type_union import TypeUnion
+from pydantic import Field, ValidationError, Extra
+
+from .base import Base
+
+
+_DT_FORMAT: str = "%Y-%m-%d-%H-%M-%S"
+_EXAMPLE_DT: str = datetime(year=1970, month=1, day=1).strftime(_DT_FORMAT)
+StrDict = dict[str, Any]
+ContentBase = str | Widget | StrDict
+Content = ContentBase | list[ContentBase]
+T = TypeVar("T")
+
+
+def now_pretty() -> str:
+    return datetime.now().strftime(_DT_FORMAT)
+
+
+class Context(Base):
+    client_id: str = Field("", examples=["543216789"])
+    user_id: str = Field("", examples=["123456789"])
+    session_id: str = Field(default_factory=now_pretty, examples=["987654321"])
+    track_id: str = Field("", examples=["Hello"])
+    extra: StrDict | None = Field(None, examples=[None])
+
+    def create_id(self, short: bool = False) -> str:
+        uid, sid, cid = self.user_id, self.session_id, self.client_id
+        if short:
+            return f"{cid}_{uid}_{sid}"
+        return f"client_{cid}_user_{uid}_session_{sid}"
+
+    def _get_deprecated_extra(self, field, default):
+        # legacy: eliminate after migration
+        res = (self.extra or {}).get(field, default)
+        warnings.warn(f"Deprecated property `{field}`, should be eliminated", stacklevel=2)
+        return res
+
+    # fmt: off
+    @property
+    def sex(self) -> bool: return self._get_deprecated_extra('sex', True)
+    @property
+    def age(self) -> int: return self._get_deprecated_extra('age', 0)
+    @property
+    def entrypoint_key(self) -> str: return self._get_deprecated_extra('entrypoint_key', '')
+    @property
+    def language_code(self) -> str: return self._get_deprecated_extra('language_code', '')
+    @property
+    def parent_session_id(self) -> str: return self._get_deprecated_extra('parent_session_id', '')
+    # fmt: on
+
+
+def _get_field(obj: dict, field, val_type: type[T]) -> T | None:
+    if not isinstance(obj, dict):
+        return None
+    val = obj.get(field)
+    if val is not None and isinstance(val, val_type):
+        return val
+    return None
+
+
+def _get_text(obj: Content) -> str:
+    if isinstance(obj, str):
+        return obj
+    if isinstance(obj, list):
+        return "".join(map(_get_text, obj))
+    if isinstance(obj, dict) and obj.get("type") == "text":
+        return _get_field(obj, "text", str) or ""
+    return ""
+
+
+def _modify_text(obj: Content, callback: Callable[[str], str | None]) -> str:
+    if isinstance(obj, str):
+        return callback(obj)
+    if isinstance(obj, list):
+        return [_modify_text(el, callback) for el in obj]
+    if isinstance(obj, dict) and obj.get("type") == "text":
+        text = _get_field(obj, "text", str) or ""
+        text_upd = callback(text)
+        return {"type": "text", "text": text_upd}
+    return obj
+
+
+def _get_resource_id(obj: Content) -> str | None:
+    if isinstance(obj, list):
+        return next((el for el in map(_get_resource_id, obj) if el), None)
+    if isinstance(obj, dict) and obj.get("type") == "resource_id":
+        return _get_field(obj, "resource_id", str)
+    return None
+
+
+def _get_command(obj: Content) -> dict | None:
+    if isinstance(obj, list):
+        return next((el for el in map(_get_command, obj) if el), None)
+    if isinstance(obj, dict) and obj.get("type") == "command":
+        return _get_field(obj, "command", dict)
+    return None
+
+
+def _get_widget(obj: Content) -> Widget | None:
+    if isinstance(obj, list):
+        return next((el for el in map(_get_widget, obj) if el), None)
+    if isinstance(obj, Widget):
+        return obj
+    return None
+
+
+# todo fix: generalize functions _get_field
+
+
+class BaseMessage(Base):
+    type: str
+    content: Content = Field("", examples=["Привет"])
+    date_time: str = Field(default_factory=now_pretty, examples=[_EXAMPLE_DT])
+    extra: StrDict | None = Field(None, examples=[None])
+
+    @property
+    def text(self) -> str:
+        return _get_text(self.content)
+
+    def modify_text(self, callback: Callable[[str], str]) -> "BaseMessage":
+        content_upd = _modify_text(self.content, callback)
+        return self.model_copy(update=dict(content=content_upd))
+
+    @property
+    def body(self) -> str:
+        # legacy: eliminate after migration
+        return self.text
+
+    @property
+    def resource_id(self) -> str | None:
+        return _get_resource_id(self.content)
+
+    @property
+    def command(self) -> dict | None:
+        return _get_command(self.content)
+
+    @property
+    def widget(self) -> Widget | None:
+        return _get_widget(self.content)
+
+    @staticmethod
+    def DATETIME_FORMAT() -> str:
+        return _DT_FORMAT
+
+    def with_now_datetime(self):
+        return self.model_copy(update=dict(date_time=now_pretty()))
+
+    @property
+    def is_ai(self):
+        return self.type == "ai"
+
+    @property
+    def is_human(self):
+        return self.type == "human"
+
+
+class HumanMessage(BaseMessage):
+    type: Literal["human"] = "human"
+
+
+class AIMessage(BaseMessage):
+    type: Literal["ai"] = "ai"
+    state: str = Field("", examples=["COLLECTION"])
+
+    @property
+    def action(self) -> str:
+        return (self.extra or {}).get("action", "")
+
+
+class MiscMessage(BaseMessage):
+    type: Literal["misc"] = "misc"
+
+
+ChatMessage = TypeUnion[HumanMessage, AIMessage, MiscMessage]
+
+
+class Chat(Base):
+    context: Context = Field(default_factory=Context)
+    messages: list[ChatMessage] = Field(default_factory=list)
+
+    class Config:
+        extra = Extra.ignore
+
+    def __init__(self, **data):
+        extra_fields = set(data.keys()) - set(self.__fields__.keys())
+        if extra_fields:
+            warnings.warn(f"Chat initialization: extra fields will be ignored: {extra_fields}")
+        super().__init__(**data)
+
+    def create_id(self, short: bool = False) -> str:
+        return self.context.create_id(short)
+
+    @staticmethod
+    def parse(chat_obj: str | dict | ChatItem) -> "Chat":
+        return _parse_chat_compat(chat_obj)
+
+    def to_chat_item(self) -> ChatItem:
+        return convert_chat_to_chat_item(self)
+
+    def add_message(self, message: ChatMessage):
+        self.messages.append(message)
+
+    def add_messages(self, messages: list[ChatMessage]):
+        for message in messages:
+            self.messages.append(message)
+
+    def replace_messages(self, messages: list[ChatMessage]):
+        return self.model_copy(update=dict(messages=messages))
+
+    def get_last_state(self, default: str = "empty") -> str:
+        for ii in range(len(self.messages) - 1, -1, -1):
+            message = self.messages[ii]
+            if isinstance(message, AIMessage):
+                return message.state
+        return default
+
+
+def make_content(
+    text: str | None = None,
+    *,
+    resource_id: str | None = None,
+    command: dict | None = None,
+    widget: Widget | None = None,
+) -> Content:
+    resource_id = (resource_id or None) and {"type": "resource_id", "resource_id": resource_id}
+    command = (command or None) and {"type": "command", "command": command}
+
+    content = list(filter(None, [text, resource_id, command, widget]))
+    if len(content) == 0:
+        content = ""
+    elif len(content) == 1:
+        content = content[0]
+
+    return content
+
+
+def convert_replica_item_to_message(replica: ReplicaItem) -> ChatMessage:
+    date_time = replica.date_time
+    content = make_content(
+        text=replica.body,
+        resource_id=replica.resource_id,
+        command=replica.command,
+        widget=replica.widget,
+    )
+    # legacy: eliminate after migration
+    resource_id = (replica.resource_id or None) and {"type": "resource_id", "resource_id": replica.resource_id}
+    body = replica.body
+    command = (replica.command or None) and {"type": "command", "command": replica.command}
+    widget = replica.widget
+    date_time = replica.date_time
+
+    content = list(filter(None, [body, resource_id, command, widget]))
+    if len(content) == 0:
+        content = ""
+    elif len(content) == 1:
+        content = content[0]
+
+    is_bot_message = replica.role
+
+    if is_bot_message:
+        kwargs = dict(
+            content=content,
+            date_time=date_time,
+            state=replica.state,
+            extra=dict(
+                **(replica.extra or {}),
+                action=replica.action,
+                moderation=replica.moderation,
+            ),
+        )
+        res = AIMessage(**kwargs)
+    else:
+        kwargs = dict(content=content, date_time=date_time)
+        res = HumanMessage(**kwargs)
+    return res
+
+
+def convert_outer_context_to_context(octx: OuterContextItem) -> Context:
+    # legacy: eliminate after migration
+    context = Context(
+        client_id=octx.client_id,
+        user_id=octx.user_id,
+        session_id=octx.session_id,
+        track_id=octx.track_id,
+        extra=dict(
+            sex=octx.sex,
+            age=octx.age,
+            parent_session_id=octx.parent_session_id,
+            entrypoint_key=octx.entrypoint_key,
+            language_code=octx.language_code,
+        ),
+    )
+    return context
+
+
+def convert_chat_item_to_chat(chat_item: ChatItem) -> Chat:
+    # legacy: eliminate after migration
+    context = convert_outer_context_to_context(chat_item.outer_context)
+    messages = list(map(convert_replica_item_to_message, chat_item.inner_context.replicas))
+    res = Chat(context=context, messages=messages)
+    return res
+
+
+def convert_context_to_outer_context(context: Context) -> OuterContextItem:
+    # legacy: eliminate after migration
+    extra = context.extra or {}
+    return OuterContextItem(
+        client_id=context.client_id,
+        user_id=context.user_id,
+        session_id=context.session_id,
+        track_id=context.track_id,
+        sex=extra.get("sex"),
+        age=extra.get("age"),
+        parent_session_id=extra.get("parent_session_id"),
+        entrypoint_key=extra.get("entrypoint_key"),
+        language_code=extra.get("language_code"),
+    )
+
+
+def convert_message_to_replica_item(message: ChatMessage) -> ReplicaItem | None:
+    # legacy: eliminate after migration
+    m_type = message.type
+    if m_type in {"ai", "human"}:
+        role = m_type == "ai"
+    else:
+        return None
+
+    extra = deepcopy(message.extra) if message.extra else {}
+    action = extra.pop("action", "")
+    moderation = extra.pop("moderation", "OK")
+
+    kwargs = dict(
+        role=role,
+        body=message.text,
+        resource_id=message.resource_id,
+        command=message.command,
+        widget=message.widget,
+        date_time=message.date_time,
+        extra=extra or None,
+        state=getattr(message, "state", ""),
+        action=action,
+        moderation=moderation,
+    )
+    return ReplicaItem(**kwargs)
+
+
+def convert_chat_to_chat_item(chat: Chat) -> ChatItem:
+    # legacy: eliminate after migration
+    return ChatItem(
+        outer_context=convert_context_to_outer_context(chat.context),
+        inner_context=dict(replicas=list(map(convert_message_to_replica_item, chat.messages))),
+    )
+
+
+def parse_chat_item_as_chat(chat_obj: str | dict | ChatItem) -> Chat:
+    # legacy: eliminate after migration
+    if isinstance(chat_obj, ChatItem):
+        chat_item = chat_obj
+    else:
+        chat_item = ChatItem.parse(chat_obj)
+    res = convert_chat_item_to_chat(chat_item)
+    return res
+
+
+def _parse_chat(chat_obj: str | dict) -> Chat:
+    if isinstance(chat_obj, dict):
+        return Chat.model_validate(chat_obj)
+
+    return Chat.model_validate_json(chat_obj)
+
+
+def is_chat_item(chat_obj: str | dict | ChatItem) -> bool:
+    if isinstance(chat_obj, ChatItem):
+        return True
+    if isinstance(chat_obj, dict):
+        return "OuterContext" in chat_obj
+    if isinstance(chat_obj, str):
+        return "OuterContext" in chat_obj
+    warnings.warn(f"Unexpected chat object: {chat_obj} :: {type(chat_obj)}")
+    return False
+
+
+def _parse_chat_compat(chat_obj: str | dict | ChatItem) -> Chat:
+    # legacy: eliminate after migration
+    if is_chat_item(chat_obj):
+        return parse_chat_item_as_chat(chat_obj)
+    try:
+        return _parse_chat(chat_obj)
+    except ValidationError as ex:
+        warnings.warn(f"Failed to parse chat: {ex}")
+        return parse_chat_item_as_chat(chat_obj)

mmar_mapi-1.0.0/src/mmar_mapi/models/chat_item.py

@@ -0,0 +1,157 @@
+from datetime import datetime
+from typing import Annotated, Any
+from collections.abc import Callable
+
+from mmar_mapi.models.widget import Widget
+from pydantic import Field, ConfigDict, BeforeValidator, AfterValidator
+
+from .base import Base
+
+
+_DT_FORMAT: str = "%Y-%m-%d-%H-%M-%S"
+_EXAMPLE_DT_0 = datetime(1970, 1, 1, 0, 0, 0)
+_EXAMPLE_DT: str = _EXAMPLE_DT_0.strftime(_DT_FORMAT)
+
+
+def now_pretty() -> str:
+    return datetime.now().strftime(ReplicaItem.DATETIME_FORMAT())
+
+
+class OuterContextItem(Base):
+    # remove annoying warning for protected `model_` namespace
+    model_config = ConfigDict(protected_namespaces=())
+
+    sex: bool = Field(False, alias="Sex", description="True = male, False = female", examples=[True])
+    age: int = Field(0, alias="Age", examples=[20])
+    user_id: str = Field("", alias="UserId", examples=["123456789"])
+    parent_session_id: str | None = Field(None, alias="ParentSessionId", examples=["987654320"])
+    session_id: str = Field("", alias="SessionId", examples=["987654321"])
+    client_id: str = Field("", alias="ClientId", examples=["543216789"])
+    track_id: str = Field(default="Consultation", alias="TrackId")
+    entrypoint_key: str = Field("", alias="EntrypointKey", examples=["giga"])
+    language_code: str = Field("ru", alias="LanguageCode", examples=["ru"])
+
+    def create_id(self, short: bool = False) -> str:
+        uid, sid, cid = self.user_id, self.session_id, self.client_id
+        if short:
+            return f"{uid}_{sid}_{cid}"
+        return f"user_{uid}_session_{sid}_client_{cid}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(by_alias=True)
+
+
+LABELS = {
+    0: "OK",
+    1: "NON_MED",
+    2: "CHILD",
+    3: "ABSURD",
+    4: "GREETING",
+    5: "RECEIPT",
+}
+
+
+def fix_deprecated_moderation(moderation):
+    if isinstance(moderation, int):
+        return LABELS.get(moderation, "OK")
+    elif isinstance(moderation, str):
+        return moderation
+    else:
+        raise ValueError(f"Unsupported moderation: {moderation} :: {type(moderation)}")
+
+
+def nullify_empty(text: str) -> str | None:
+    return text or None
+
+
+class ReplicaItem(Base):
+    body: str = Field("", alias="Body", examples=["Привет"])
+    resource_id: Annotated[str | None, AfterValidator(nullify_empty)] = Field(
+        None, alias="ResourceId", examples=["<link-id>"]
+    )
+    widget: Widget | None = Field(None, alias="Widget", examples=[None])
+    command: dict | None = Field(None, alias="Command", examples=[None])
+    role: bool = Field(False, alias="Role", description="True = ai, False = client", examples=[False])
+    date_time: str = Field(
+        default_factory=now_pretty, alias="DateTime", examples=[_EXAMPLE_DT], description=f"Format: {_DT_FORMAT}"
+    )
+    state: str = Field("", alias="State", description="chat manager fsm state", examples=["COLLECTION"])
+    action: str = Field("", alias="Action", description="chat manager fsm action", examples=["DIAGNOSIS"])
+    # todo fix: support loading from `moderation: int`
+    moderation: Annotated[str, BeforeValidator(str)] = Field(
+        "OK", alias="Moderation", description="moderation outcome", examples=["OK"]
+    )
+    extra: dict | None = Field(None, alias="Extra", examples=[None])
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(by_alias=True)
+
+    @staticmethod
+    def DATETIME_FORMAT() -> str:
+        return _DT_FORMAT
+
+    def with_now_datetime(self):
+        return self.model_copy(update=dict(date_time=now_pretty()))
+
+    @property
+    def is_ai(self):
+        return self.role
+
+    @property
+    def is_human(self):
+        return not self.role
+
+    def modify_text(self, callback: Callable[[str], str]) -> "ReplicaItem":
+        body_upd = callback(self.body)
+        return self.model_copy(update=dict(body=body_upd))
+
+
+class InnerContextItem(Base):
+    replicas: list[ReplicaItem] = Field(alias="Replicas")
+    attrs: dict[str, str | int] | None = Field(default={}, alias="Attrs")
+
+    def to_dict(self) -> dict[str, list]:
+        return self.model_dump(by_alias=True)
+
+
+class ChatItem(Base):
+    outer_context: OuterContextItem = Field(alias="OuterContext")
+    inner_context: InnerContextItem = Field(alias="InnerContext")
+
+    def create_id(self, short: bool = False) -> str:
+        return self.outer_context.create_id(short)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(by_alias=True)
+
+    def add_replica(self, replica: ReplicaItem):
+        self.inner_context.replicas.append(replica)
+
+    def add_replicas(self, replicas: list[ReplicaItem]):
+        for replica in replicas:
+            self.inner_context.replicas.append(replica)
+
+    def replace_replicas(self, replicas: list[ReplicaItem]):
+        return self.model_copy(update=dict(inner_context=InnerContextItem(replicas=replicas)))
+
+    def get_last_state(self, default: str = "empty") -> str:
+        replicas = self.inner_context.replicas
+        for ii in range(len(replicas) - 1, -1, -1):
+            replica = replicas[ii]
+            if replica.role:
+                return replica.state
+        return default
+
+    def zip_history(self, field: str) -> list[Any]:
+        return [replica.to_dict().get(field, None) for replica in self.inner_context.replicas]
+
+    @classmethod
+    def parse(cls, chat_obj: str | dict) -> "ChatItem":
+        return _parse_chat_item(chat_obj)
+
+
+def _parse_chat_item(chat_obj: str | dict) -> ChatItem:
+    if isinstance(chat_obj, dict):
+        return ChatItem.model_validate(chat_obj)
+
+    return ChatItem.model_validate_json(chat_obj)

mmar_mapi-1.0.0/src/mmar_mapi/models/enums.py

@@ -0,0 +1,40 @@
+from enum import StrEnum, auto
+
+
+class DoctorChoiceXMLTagEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name: str, start: int, count: int, last_values: list[str]) -> str:
+        return f"{name.lower()}"
+
+    DIAGNOSTICS = auto()
+    SUMMARIZATION = auto()
+    MTRS = auto()
+
+
+class MTRSXMLTagEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name: str, start: int, count: int, last_values: list[str]) -> str:
+        return f"mtrs_{name.lower()}"
+
+    NAME = auto()
+    LABEL = auto()
+    DESC = auto()
+
+
+class MTRSLabelEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name: str, start: int, count: int, last_values: list[str]) -> str:
+        return name.upper()
+
+    LABORATORY = auto()
+    INSTRUMENTAL = auto()
+
+
+class DiagnosticsXMLTagEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name: str, start: int, count: int, last_values: list[str]) -> str:
+        return f"diag_{name.lower()}"
+
+    DIAG = auto()
+    DOC = auto()
+    DESC = auto()

mmar_mapi-1.0.0/src/mmar_mapi/models/tracks.py

@@ -0,0 +1,14 @@
+from pydantic import Field
+
+from .base import Base
+
+
+class TrackInfo(Base):
+    track_id: str = Field(alias="TrackId")
+    name: str = Field(alias="Name")
+    domain_id: str = Field(alias="DomainId")
+
+
+class DomainInfo(Base):
+    domain_id: str = Field(alias="DomainId")
+    name: str = Field(alias="Name")

mmar_mapi-1.0.0/src/mmar_mapi/models/widget.py

@@ -0,0 +1,22 @@
+from typing import Self, Literal
+
+from pydantic import BaseModel, model_validator
+
+
+class Widget(BaseModel):
+    type: Literal["widget"] = "widget"
+    buttons: list[list[str]] | None = None
+    ibuttons: list[list[str]] | None = None
+
+    @model_validator(mode="after")
+    def check(self) -> Self:
+        if not self.buttons and not self.ibuttons:
+            raise ValueError("Empty widget is not allowed!")
+        if not self.ibuttons:
+            return self
+        for row in self.ibuttons:
+            for btn in row:
+                if ":" in btn:
+                    continue
+                raise ValueError(f"Expected buttons like `<callback>:<caption>`, found: {btn}")
+        return self

mmar_mapi-1.0.0/src/mmar_mapi/type_union.py

@@ -0,0 +1,63 @@
+from typing import Any, Union, Annotated, get_args, get_origin, Literal
+
+from pydantic import Discriminator, BaseModel, Tag
+
+
+class _TypeUnionMeta(type):
+    def __getitem__(cls, types):
+        if not isinstance(types, tuple):
+            types = (types,)
+
+        for tp in types:
+            if not isinstance(tp, type) or not issubclass(tp, BaseModel):
+                raise ValueError(f"Type {tp} must derived from BaseModel")
+
+        # Create tagged union
+        tagged_types = []
+        type_map = {}
+        type_names = set()
+        for t in types:
+            type_annot = t.__annotations__.get("type")
+            if not type_annot or get_origin(type_annot) != Literal:
+                raise ValueError(f"Type {t} must have a 'type' Literal[..] field for discrimination")
+            type_name = get_args(type_annot)[0]
+            type_map[type_name] = t
+            tagged_types.append(Annotated[t, Tag(type_name)])
+            type_names.add(type_name)
+
+        # Create the union type
+        union_type = Union[tuple(tagged_types)]
+
+        # Create discriminator function
+        def type_discriminator(v: Any) -> str:
+            if isinstance(v, types):
+                return v.type
+            if isinstance(v, dict):
+                tp = v.get("type")
+                return tp if tp in type_names else None
+            return None
+
+        # Add discriminator
+        return Annotated[union_type, Discriminator(type_discriminator)]
+
+
+class TypeUnion(metaclass=_TypeUnionMeta):
+    """
+    Wrapper around Union which derive type from field 'type' for effective deserialization via TypeAdapter.
+
+    Usage example:
+    ```
+    class BaseFruit(BaseModel):
+        type: str
+
+    class Apple(BaseFruit):
+        type: Literal['apple'] = 'apple'
+
+    class Orange(BaseFruit):
+        type: Literal['orange'] = 'orange'
+
+    Fruit = TypeUnion[Apple, Orange]
+    ```
+    """
+
+    pass

mmar_mapi-1.0.0/src/mmar_mapi/utils.py

@@ -0,0 +1,5 @@
+from datetime import datetime
+
+
+def make_session_id() -> str:
+    return f"{datetime.now():%Y-%m-%d--%H-%M-%S}"