Skip to content
Docs

Documentation navigation

Messages

Message types and semantics used across invocations.

#Messages

The public message helpers live in maivn.messages and convert to the owned maivn_contracts.messages.Message wire contract.

Privacy controls are not certifications. Redaction and whitelist controls reduce exposure; they do not guarantee every private value is detected. mAIvn holds no SOC 2, HIPAA, ISO 27001, or FedRAMP certification, cannot provide a BAA, and does not make a deployment compliant. Evaluate and use the controls at your own risk under the mAIvn Platform Disclaimer.

#Imports

Python 
from maivn.messages import (
    AIMessage,
    BaseMessage,
    HumanMessage,
    PrivateData,
    RedactedMessage,
    SystemMessage,
    ToolMessage,
    to_contract_messages,
)
from maivn_contracts.messages import Attachment, ContentBlock, Message, RedactionConfig

#Convenience messages

HumanMessage, AIMessage, SystemMessage, and ToolMessage are frozen Pydantic models with fixed roles. Their shared shape is:

Plain text 
content: str | list[ContentBlock]
role: MessageRole
message_id: str = generated
attachments: Sequence[Attachment | Mapping[str, object]] | None = None
redaction: RedactionConfig | None = None
metadata: dict[str, MetadataValue] | None = None
ts: str = generated UTC timestamp
Python 
from maivn.messages import HumanMessage, SystemMessage

messages = [
    SystemMessage(content='Answer concisely.'),
    HumanMessage(content='Summarize this ticket.'),
]
response = agent.invoke(messages)

BaseMessage.to_contract() returns a validated wire Message. to_contract_messages(...) accepts one string/message or a sequence and normalizes everything to list[Message].

#Attachments

Message constructors accept contract Attachment objects or dictionaries. A storage-backed dictionary supplies storage_ref, content_hash, filename, MIME type, and size. An inline dictionary supplies one of inline_base64, content_base64, content_bytes, or text_content; the SDK derives base64, size, and SHA-256 where needed.

Python 
from maivn.messages import HumanMessage

message = HumanMessage(
    content='Use the attached runbook.',
    attachments=[
        {
            'filename': 'runbook.txt',
            'mime_type': 'text/plain',
            'text_content': 'Rollback if canary checks fail.',
        }
    ],
)

Local file-path loading is not a message-constructor feature. Read an authorized file yourself and pass bytes/base64, or register it through the SDK resource APIs.

#PrivateData and RedactedMessage

PrivateData is a frozen descriptor with required value: object plus optional name, pii_type, label, description, and format fields.

RedactedMessage accepts text or content blocks, optional known PII values, a whitelist, attachments, metadata, message ID, and timestamp:

Python 
from maivn import PIIWhitelist, PIIWhitelistEntry
from maivn.messages import PrivateData, RedactedMessage

whitelist = PIIWhitelist(
    entries=(
        PIIWhitelistEntry(
            value='support@maivn.io',
            justification='Published support address.',
        ),
    )
)

message = RedactedMessage(
    content='Contact Maria at maria@example.com or support@maivn.io.',
    known_pii_values=[PrivateData(value='Maria', name='customer_name')],
    pii_whitelist=whitelist,
)

Each PIIWhitelistEntry requires exactly one of entity_type, pattern, or value, plus a justification of 8–512 characters. phi_mode=True rejects category-wide entries for exported HIPAA_SAFE_HARBOR_CATEGORIES; it is a technical category guard, not a compliance guarantee.

RedactedMessage.to_contract() returns a user-role Message with a RedactionConfig carrying the known values and whitelist.

See Private Data for execution-time injection and control limitations.